Skip to content

feat(reporting): bind package source coverage to media buys - #1928

Open
rachitm022 wants to merge 2 commits into
nextfrom
rachitm022/ai-22388-contract
Open

rachitm022 wants to merge 2 commits into
nextfrom
rachitm022/ai-22388-contract

Conversation

@rachitm022

@rachitm022 rachitm022 commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Package reporting needs a source request that freezes the selected media buys and the exact (media_buy_id, package_id) pairs. A completed scan can have no packages while still proving which buys were scanned.

What changed

  • Extend the single V1 request and manifest schema conditionally for coverage.grain == "package_item". Package scope requires a nonempty unique media_buy_ids selector and unique pair constituents; the selector and pairs are bound into the denominator and manifest content fingerprints.
  • Preserve ordinary product and media-buy V1 serialization and fingerprints byte for byte when package fields are absent. Frozen request JSON, denominator, and manifest hash regressions cover this path.
  • Accept a dated, fully covered empty package scope with zero rows and metric cells, while retaining the 1,000 constituent-metric cell limit.
  • Validate package rows before staging and at final admission against the exact requested pairs. Both paths reject duplicate (media_buy_id, package_id, requested dimension values) rows and allow distinct requested dimension values.
  • Require package-item capability for package scope even when the pair set is empty. The source response, capability, request, and manifest all remain version 1.0.

Beta migration

Package source adapters must include media_buy_id on every PackageItemConstituentV1, and package requests must set coverage.grain="package_item" and list the selected coverage.media_buy_ids. Earlier beta package requests without these fields will fail validation. Product and media-buy V1 requests keep their existing JSON and fingerprints.

Verification

  • make lint — passed.
  • make typecheck-all — passed.
  • make test in an isolated Ubuntu 24.04 container with Python 3.12.3, Node 22.12.0, and uv 0.12.8 — 22,042 passed, 3,050 skipped, 10 deselected, 1 xfailed; 91.94% coverage; exit 0.
  • The seven tests that failed on the macOS host passed in Linux. A first Linux run hit a 4 GiB container limit; a second exposed missing python3 and jq utilities in the minimal image. After those environment corrections, the full Linux run passed on identical source bytes.
  • git diff --check — passed. Frozen source patch SHA256: 6735bf7f900a980af1edb3723d0f91d036431c650cc42eac43f0c1f1a26ab96f.

Integration

Jakarta's follow-up producer, inline source, and store admission patch consumes the V1 package API. This source-contract PR is ready for review. No package activation or release is included.

Tracks AI-22388.

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — additive V2 package-aware reporting-source contract, no blocking findings.

What I checked:

  • No no-auto-approve team match; gated_paths: false; high_risk: false; first review of this PR.
  • Semver signal: V2 classes subclass V1; __all__ only gains entries (no removals/renames), so feat(reporting): is the correct non-breaking prefix — no public-surface break ships under a non-breaking signal.
  • DR-0032/33 version pathway is "Refused": version-negotiation gate in _validate_request_against_capabilities and manifest/response checks fail-closed on mismatch, and this is covered (test_v2_only_capability_rejects_v1_request, test_one_executor_can_negotiate_v1_and_v2_requests, test_mixed_request_manifest_versions_fail_admission).
  • Fingerprint identity binding verified: publication_content_fingerprint_v2 and coverage_denominator_fingerprint_v2 bind media_buy_ids/pairs so distinct buys yield distinct fingerprints even on empty coverage.
  • Row-fencing/explicit_zero logic, unique-package-pair enforcement, and strict echo of media_buy_ids/constituents all checked and safe; heavily tested (756-line contract test file).

Reviewer found no Critical/High/Medium findings. No decision-table trigger fired (rows 1–8 all negative), so this falls through to row 9 → approve.

@rachitm022
rachitm022 marked this pull request as draft November 19, 2026 18:27
@rachitm022
rachitm022 marked this pull request as ready for review November 19, 2026 21:21
Comment thread src/adcp/reporting/source.py Resolved

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Comment (human reviewer recommended)

Comment — 1 medium finding; wire-shape change to a public model warrants a human eye on the semver signal.

The reviewer found no critical/high findings. The one medium concern: a new required media_buy_id on the exported PackageItemConstituentV1 (plus now-mandatory package grain/media_buy_ids) is a wire-shape change to a released public model, shipped under feat(reporting): rather than feat!:/BREAKING CHANGE: with no migration note. The reviewer graded this Medium (not High) because the 10.0.0-beta train folds the change into 10.0.0, muting the minor-cut harm that would normally make an unmarked break a high finding.

Why not approve: although a single medium finding normally falls through to row 9 (approve), this sits directly on the repo's mandatory semver-signal gate for public-surface wire-shape changes. The reviewer's own grading hinges on the release train being pre-1.0-style beta; a human should confirm the beta-train assumption holds before this merges so the break genuinely lands under a major and not a stray minor.

Note: the decision table (row 8) reserves comment for 3+ medium findings. Strictly applied, 1 medium with no other trigger is an approve. Flagging the semver/migration-note question for human confirmation given the public-model wire change.

Medium findings

  • src/adcp/reporting/source.py:515 — New required media_buy_id on exported PackageItemConstituentV1 shipped under feat: not feat!:; no migration note.

Prior pass was clean (no findings).

Medium findings

  • src/adcp/reporting/source.py:515 — New required media_buy_id on exported PackageItemConstituentV1 shipped under feat: not feat!:

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant